# @Version        : 1.0
# @Update Time    : 2025/10/15 00:00
# @File           : storage_interface.py
# @IDE            : PyCharm
# @Desc           : 存储接口定义
from typing import Any, Optional, List, Dict, Set
from abc import ABC, abstractmethod


class StorageInterface(ABC):
    """
    存储接口
    定义数据存储和检索的基础操作
    """

    @abstractmethod
    def get(self, key: str) -> Optional[Any]:
        """
        获取指定key的值

        Args:
            key: 键名

        Returns:
            值，如果不存在返回None
        """
        pass

    @abstractmethod
    def set(self, key: str, value: Any, timeout: Optional[int] = None) -> bool:
        """
        设置key-value

        Args:
            key: 键名
            value: 值
            timeout: 过期时间（秒）

        Returns:
            是否设置成功
        """
        pass

    @abstractmethod
    def delete(self, key: str) -> bool:
        """
        删除指定key

        Args:
            key: 键名

        Returns:
            是否删除成功
        """
        pass

    @abstractmethod
    def exists(self, key: str) -> bool:
        """
        判断key是否存在

        Args:
            key: 键名

        Returns:
            是否存在
        """
        pass

    @abstractmethod
    def get_keys(self, pattern: str) -> List[str]:
        """
        获取所有匹配pattern的key

        Args:
            pattern: 匹配模式

        Returns:
            匹配的key列表
        """
        pass

    @abstractmethod
    def delete_keys(self, pattern: str) -> int:
        """
        删除所有匹配pattern的key

        Args:
            pattern: 匹配模式

        Returns:
            删除的key数量
        """
        pass

    @abstractmethod
    def set_expire(self, key: str, timeout: int) -> bool:
        """
        设置key的过期时间

        Args:
            key: 键名
            timeout: 过期时间（秒）

        Returns:
            是否设置成功
        """
        pass

    @abstractmethod
    def get_expire(self, key: str) -> int:
        """
        获取key的剩余过期时间

        Args:
            key: 键名

        Returns:
            剩余过期时间（秒），-1表示永不过期，-2表示不存在
        """
        pass

    @abstractmethod
    def increment(self, key: str, amount: int = 1) -> int:
        """
        自增操作

        Args:
            key: 键名
            amount: 增量

        Returns:
            自增后的值
        """
        pass

    @abstractmethod
    def decrement(self, key: str, amount: int = 1) -> int:
        """
        自减操作

        Args:
            key: 键名
            amount: 减量

        Returns:
            自减后的值
        """
        pass

    @abstractmethod
    def hget(self, key: str, field: str) -> Optional[Any]:
        """
        获取哈希表中指定字段的值

        Args:
            key: 键名
            field: 字段名

        Returns:
            字段值，如果不存在返回None
        """
        pass

    @abstractmethod
    def hset(self, key: str, field: str, value: Any) -> bool:
        """
        设置哈希表中指定字段的值

        Args:
            key: 键名
            field: 字段名
            value: 值

        Returns:
            是否设置成功
        """
        pass

    @abstractmethod
    def hgetall(self, key: str) -> Dict[str, Any]:
        """
        获取哈希表中所有字段和值

        Args:
            key: 键名

        Returns:
            所有字段和值的字典
        """
        pass

    @abstractmethod
    def hdel(self, key: str, field: str) -> bool:
        """
        删除哈希表中指定字段

        Args:
            key: 键名
            field: 字段名

        Returns:
            是否删除成功
        """
        pass

    @abstractmethod
    def hkeys(self, key: str) -> List[str]:
        """
        获取哈希表中所有字段名

        Args:
            key: 键名

        Returns:
            字段名列表
        """
        pass

    @abstractmethod
    def sadd(self, key: str, *values: Any) -> int:
        """
        向集合中添加一个或多个成员

        Args:
            key: 键名
            values: 要添加的成员

        Returns:
            添加成功的成员数量
        """
        pass

    @abstractmethod
    def srem(self, key: str, *values: Any) -> int:
        """
        从集合中移除一个或多个成员

        Args:
            key: 键名
            values: 要移除的成员

        Returns:
            移除成功的成员数量
        """
        pass

    @abstractmethod
    def sismember(self, key: str, value: Any) -> bool:
        """
        判断成员是否在集合中

        Args:
            key: 键名
            value: 成员

        Returns:
            是否存在
        """
        pass

    @abstractmethod
    def smembers(self, key: str) -> Set[Any]:
        """
        获取集合中的所有成员

        Args:
            key: 键名

        Returns:
            成员集合
        """
        pass

    @abstractmethod
    def close(self) -> None:
        """
        关闭存储连接
        """
        pass
